﻿<!DOCTYPE html>
<html>
  <head>
    <meta name="generator" content="h-smile:richtext"/>
  </head>
<body>
  <h1>The Plus Framework</h1>
  <p>Main goal of the Plus is to provide declarative data binding facilities - data (model) can be bound with its HTML representation in various ways.</p>
  <h2>Model declaration, the <em>model</em> attribute</h2>
  <p>Any DOM element-container can be linked with some namespace (object) that contains data (a.k.a. model) to be viewed inside the container. Such a link is established by special model attribute:</p>
  <pre>&lt;body model=&quot;MyDataNamespace&quot;&gt;
   ...
&lt;/body&gt;
</pre>
  <p>And if you have in your script this:</p>
  <pre>namespace MyDataNamespace {
   ...
}
</pre>
  <p>then content of the body element (in this case) can be linked (bound) with the data in MyDataNamespace.</p>
  <p>Topmost element that has such model attribute is known as a <em>data model view</em> - elements bound with the model data namespace / object reflect state of the data.</p>
  <h2>Bound elements</h2>
  <p>Element's value can be bound with some variable in the model. +plus framework uses attribute <em>name</em> that shall contain name or expression to bind with.</p>
  <pre>&lt;body model=&quot;Data&quot;&gt;
  &lt;p&gt;Whom to greet: &lt;input|text(greeting) /&gt;&lt;/p&gt;
  &lt;p&gt;Greeting: Hello &lt;output(greeting) /&gt;!&lt;/p&gt;
&lt;/body&gt;
</pre>
  <p>Two elements above are bound with the same variable <code>Data.greeting</code> in the model. Changes in the &lt;input&gt; element are reflected in the &lt;output&gt; element.</p>
  <p>Normally data variable is bound with the <code>value</code> property of linked element directly. But if the element has <code>setBoundValue(newVal)</code> defined (on it or its behavior class) then the function will be called to set the value.</p>
  <h2>Bound attributes</h2>
  <p>Sciter also suppports attribute value binding with variables and object properties. To define bound attribute simply add '@' character in front of its name and provide variable name or expression as a value of the attribute:</p>
  <pre>&lt;li&gt;&lt;picture @src=&quot;customer.image&quot; /&gt; &lt;output(customer.name)/&gt;&lt;/li&gt;
</pre>
  <p>Here <code>src</code> attribute will be bound with <code>customer.image</code> variable and the ouput will contain value of <code>customer.name</code> variable.</p>
  <p>There are bound attributes that are mapped to state flags:</p>
  <ul>
    <li><code>@enabled=&quot;expression&quot;</code> - boolean expression is bound as element.state.disabled = !expression;</li>
    <li><code>@disabled=&quot;expression&quot;</code> - boolean expression is bound to element.state.disabled = expression;</li>
    <li><code>@expanded=&quot;expression&quot;</code> - boolean expression is bound as element.state.expanded = expression;</li>
    <li><code>@collapsed=&quot;expression&quot;</code> - boolean expression is bound as element.state.collapsed = expression;</li></ul>
  
	<h2>Repeatables</h2><h3><code>each</code> repeatable</h3>
  <p>Any container may have attribute <b>each=&quot;<em>item</em> in <em>items</em>&quot;</b> defined. In this case initial content of the container is used as a template markup that will be repeated for each element in items collection. Format of the <em>each</em> attribute:</p>
  <pre>[{index},]{item} <strong>in</strong> {items-expression} [ <strong>|</strong> {filter-expression}
</pre>
  <p>where:</p>
  <ul>
    <li><code>{item}</code> - arbitrary name of variable that represents current item in repeatable section;</li>
    <li><code>{index}</code> - optional, variable name that receives integer - index of the item in items array;</li>
    <li><code>{items-expression}</code> - name of variable in model or expression that resolves to some array - list of objects to render by this repeatable.</li>
    <li><code>{filter-expression}</code> - optional, literal or nametoken that is resolved to a filter. Filter can be either:</li>
    <ul>
      <li><code>null</code> (or simply omitted) - no filter is set, all elements are rendered;</li>
      <li><code>object</code> (including object literal) - all elements matching that object are included into output;</li>
      <li><code>&quot;string&quot;</code> - if any string property in the item contains the string - the item gets rendered.</li>
      <li><code>function</code> having signature <code>function(item, index)</code>. That&nbsp;function to be called for each item, if it returns <em>true</em> - record gets rendered;
      <p>The function is called with its <code>this</code> variable set to the Repeatable container element (the one that has <i>each</i> attribute defined). This allows filter function to access DOM environment.</p></li>
      </ul></ul>
  <p>Example of the list that renders myCustomers items as list items:</p>
  <pre>  &lt;ol each=&quot;customer in myCustomers&quot;&gt;
      &lt;li&gt;&lt;picture @src=&quot;customer.image&quot; /&gt; &lt;output(customer.name)/&gt;&lt;/li&gt;
  &lt;/ol&gt;
</pre>
  <p>Example of list with filter function:</p>
	<pre>  &lt;ol each=&quot;customer in myCustomers|myFilterFunction&quot;&gt;
      &lt;li&gt;&lt;picture @src=&quot;customer.image&quot; /&gt; &lt;output(customer.name)/&gt;&lt;/li&gt;
  &lt;/ol&gt;
</pre>
  <p>Note that myFilter name gets resolved to&nbsp;myFilter&nbsp;variable / function defined in closest <i>namespace</i> to&nbsp;<code>myCustomers</code>.&nbsp;</p>
	<h3><code>repeat</code> repeatable</h3>
	
	<p>This kind of repeatable uses <code>repeat</code> attribute   on the element that itself needs to be replicated:&nbsp;</p><pre> &lt;ol&gt;
   &lt;li repeat=&quot;customer in myCustomers&quot;&gt;
      &lt;picture @src=&quot;customer.image&quot; /&gt; &lt;output(customer.name)/&gt;
   &lt;/li&gt; 
 &lt;/ol&gt;</pre>
	<p>Where <code>repeat</code> attribute uses the same syntax as <code>each</code> above.&nbsp;</p>
	<p>In some cases repeat form of the repeatable is more convenient than each.&nbsp;</p><h2>Observing changes on data paths</h2><p>The Plus defines <code>@observing</code> decorator that can be used to subscribe functions on particular changes in model data tree. Syntax of declaring such subscriptions:</p>
<pre>@observing &quot;path&quot; [&quot;path2&quot;[,&nbsp;... &quot;pathN&quot; ]] 
  function(path) {
      
  }</pre>
<p>Where <i>path</i> is a&nbsp;string separated by <code>.</code> (dot) and <code>[]</code> (if element on the path is an array).</p><p>The function gets called with <i>this</i> set to rightmost object or array on the path.</p><p>Example:</p>
<pre>namespace Data 
{ 
   var items = [
       { name:&quot;Alan&quot;, state: true },
       { name:&quot;Winston&quot;, state: false }
   ];

   @oberving &quot;items[].state&quot; function() {
      // .state property was changed in one of items
      // 'this' here is the item
   }
}</pre>
<h2>Basic event handlers</h2>
  <p>Elements may contain one of event attributes defining function to be executed on corresponding action. The handler function is called with <code>this</code> set to the DOM element and first parameter set to bound object.</p>
  <p>List of event attributes: &quot;click&quot;, &quot;dblclick&quot;, &quot;change&quot;, &quot;enter&quot;, &quot;escape&quot;, &quot;focusin&quot;, &quot;focusout&quot;.</p>
  <p>Example:</p>
  <pre>  &lt;b click=&quot;items.removeByValue(item)&quot;&gt;x&lt;/b&gt;
</pre>
  <p>Click on such <code>&lt;b&gt;</code> element will call <code>items.removeByValue()</code> function passing it current item object.</p>
  <h2>Sub-models</h2>
  <p>Main data model view element may have inner elements with <em>model</em> attribute - sub-views that are looking on parts of data tree.</p>
  <pre>namespace MyDataNamespace
{
  var records = [ {name: &quot;first&quot;, ...},<br/>                  {name: &quot;second&quot;, ...},
                  {name: &quot;third&quot;, ...} ];

  var <u>currentRecord</u> = {}; // used as sub-model;

  // function to set current record
  function setCurrentRecord(index) { currentRecord = records[index]; }
}
</pre>
  <p>Having such a model we can define sub-view element looking on sub-object or namespace inside the model ():</p>
  <pre>&lt;body model=&quot;MyDataNamespace&quot;&gt;
   &lt;!-- records list --&gt;
   &lt;ol each=&quot;index,record in records&quot;&gt;
      &lt;li&gt;&lt;output(record.name) click=&quot;setCurrentRecord(index)&quot; /&gt;&lt;/li&gt;
   &lt;/ol&gt;
   &lt;!-- current record view --&gt;
   &lt;section #record-details-view <u>model=&quot;currentRecord&quot;</u>&gt;
      &lt;input(name) /&gt;
      ...
   &lt;/section&gt;
&lt;/body&gt;
</pre>
  <p>Sub-view elements are observing change of [sub-] model variable, therefore as soon as the variable changes all observing elements get rebound with new data.</p>
  <p>In the example above click on the <em>output(name)</em> element in the list will cause currentRecord to be set to new object by calling &nbsp;<code>setCurrentRecord()</code> on click. See demos/L-list-detail.htm example.</p>
</body>
</html>